home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Deutsche Edition 1
/
Deutsche Edition 1.iso
/
amok
/
011-020
/
amok19
/
dossupport
/
dossupport.doc
< prev
next >
Wrap
Text File
|
1993-11-04
|
6KB
|
178 lines
======================================================================
Documentation for module "DosSupport" revision 1.3
Author: Nicolas Benezan, Postwiesenstr. 2, 7000 Stuttgart 60, Germany
======================================================================
Copyright remarks
(C) Copyright 1988 by Nicolas Benezan. All rights reserved.
The whole package (source, documentation and code) is donated to
public domain and may be copied and redistributed providing that...
* my name and this copyright remark and
* the completeness of the package remain intact,
* it's distributet for non-profit only.
Commercial use without my explicit, written permission is not
allowed. Contact me to get it and, perhaps, to pay some fee.
Improvements and new ideas are welcome, as long as the changes are
well documented inline and in the documentation files. I´would like
to know, if you make major changes and repost it.
Contents
* Package
* Introduction
* Data types
* Procedures
* Segments
* Additional hints
* Referenced literature
Package
The whole package "DosSupport" consists of following files:
* DosSupport.doc This documentation file
* DosSupport.dok German documentation
* DosSupport.def Definition module
* DosSupport.mod Implementation module
* DosSupport.sym Symbol file
* DosSupport.obj Compiled object code
Introduction
For some mysterious reason there are two competing Systems inside your
Amiga: Exec (written in C) and AmigaDos (written in BCPL). For some
even more mysterious reason, BCPL uses Pointers which are not simple
Address easily accessible to the CPU but Adresses divided by 4.
This discrepancy is very underdocumented and if you don't cope with
it, it will bring you lots of hours of meditation...
The module "DosSupport" suplies Procedures to convert the pointer-
types into one another.
The new version 1.1 contains some additional stuff necessary to deal
with "Hunks" and "Segments". The AmigaDos load file format (Hunks)
is described in [1]. You may also read the chapter "Segments" of
this documentation.
Data types
BCPL types
----------
ADDRESS: simple memory address (byte address) as used by the 68000 CPU
BPTR (BCPL-pointer): an address divided by 4, also called
longword-address. All items referenced by such pointers must
begin at an address which is a multiple of 4.
C/Modula string: several ASCII-characters (ARRAY OF CHAR) followed by
an ASCII.nul as termination mark.
BSTR (BCPL string): BCPL-pointer to a byte which contains the number
of characters that follow this byte.
In other words:
There is an ARRAY [0..m] OF CHAR. Array[1]..Array[n] contain
the actual characters. Array[0] contains CHAR(n), it tells
us how many characters this string has. Finaly, there's
a BCPL-pointer which is equal to ADR(Array) DIV 4.
(it's terrible, isn't it).
Device list types
-----------------
The new TYPE "DeviceListPtr" was added to simplify the use of the
Dos.DeviceList in Modula-2. Be careful and don't mix it up with the TYPE
"DeviceListPtr" in module Dos (it's a BPTR).
The entry "startup" of a "Dos.DeviceList"-RECORD is not a LONGINT but a
BCPL-pointer to a "StartupInfo"-RECORD, which itself contains a BPTR to a
"DiskInfo"-RECORD. Both RECORDS contain important information about the
disk device (see Mountlist).
Procedures
BPTRtoADR()
-----------
converts a BCPL-pointer into a Modula-ADDRESS
ADRtoBPTR()
-----------
does the reverse (be careful, the ADDRESS must be a multiple of 4)
BSTRtoStr()
-----------
copies a BSTR into a Modola-string (ARRAY OF CHAR) providing the final
ASCII.nul
StrToBCPL()
-----------
converts a Modula-string into a BCPL-String by shifting the characters
one position right and writing the string's length into the first
byte. You get a real BSTR by the expression
ADRtoBPTR(ADR(convertedString)).
GetDevList()
------------
returns a (Modula-) pointer to the first entry of the Dos' DeviceList.
In this list you will find all Volumes, Devices an assigned Directories
currently available. Be careful, the entries are linked by BPTRs rather
than Modula-pointers (DeviceList.next is of type BPTR).
Don't forget to Forbid() while accessing the list.
Segments
If an executable program is loaded into memory via Dos.LoadSeg() it is
devided into segments, depending on the number of hunks it consists of,
and scattered across memory. LoadSeg returns a BCPL-pointer (BPTR) to
the first Segment of a linked list. It points to one longword BEFORE
the beginning of the first code or data section. this longword contains
a BPTR to the longword before the next segment and so on. Two longwords
before the beginning of each segment there is a longword containing
the size of that segment in bytes including the two additional longwords.
In Modula it would be difficult to access the segments because of the
negative offsets of the two longwords described above and the BPTRs.
Fields of RECORDs can only have positive offsets in Modula-2. The
Procedure GetSegmentAddr() simpifies the handling of BPTRs and ADDRESSes
of segments.
VAR Seg:SegmentPtr;
...
Seg:=GetSegmentAddr(LoadSeg(...));
can be used to get a pointer to the first loaded segment.
Seg:=GetSegmentAddr(Seg^.nextSegment);
points to the next segment (or is NIL, if no further segment exists).
To get the size of the data or code section of a segment, use
Size:=Seg^.segmentSize-8; (* 8=2*SIZE(LONGWORD) *).
Some Hints..
DosSupport exports DosBase which is normally very difficult to access
in Modula. (Do not modify it!)
If you're working with a old compiler manual (version v3.1 or before)
you might have a wrong listing of the Dos' definition module. All
BPTRs and BSTRs are declared as ADDRESS in those manuals. Please watch
out for an update (version 3.11 or better V3.2).
Referenced literature
[1] "AmigaDos Technical Reference Manual", CBM, Chapter 2.2
or "AmigaDos Manual", Bantam Books
[2] "Amiga Rom Kernel Reference Manual: Exec",
Appendix B: AmigaDos general information, CBM, Addison Wesley